Configuration

Catalyst uses config/config.json for all application configuration. This file controls server settings, environment variables, universal app settings, and more.

Configuration File Location

project-root/
  └── config/
      └── config.json

Server Configuration

Server Variables

All variables in config.json are available on the server through process.env.VARIABLE_NAME.

Environment Variables

Client Variables

By default, variables are server-only. To expose a variable to client-side code, add its key to the CLIENT_ENV_VARIABLES array:

{
  "API_URL": "https://api.example.com",
  "ANALYTICS_ID": "UA-123456",
  "SECRET_KEY": "do-not-expose",
  "CLIENT_ENV_VARIABLES": ["API_URL", "ANALYTICS_ID"]
}

// Client-side usage
const apiUrl = process.env.API_URL;       // "https://api.example.com"
const analyticsId = process.env.ANALYTICS_ID; // "UA-123456"
const secret = process.env.SECRET_KEY;    // undefined (not exposed)

Security Warning: Variables in CLIENT_ENV_VARIABLES are visible in the browser. Never expose secrets, API keys with write access, or database credentials.

Universal App Configuration

The WEBVIEW_CONFIG object controls universal app settings for iOS and Android.

App Name

Configure the display name of your application that appears in device launchers, app stores, and system settings.

{
  "WEBVIEW_CONFIG": {
    "android": {
      "appName": "My Awesome App"
    },
    "ios": {
      "appName": "My Awesome App"
    }
  }
}

Splash Screen

Configure a custom splashscreen for your universal app.

{
  "WEBVIEW_CONFIG": {
    "splashScreen": {
      "duration": 2000,
      "backgroundColor": "#ffffff",
      "imageWidth": 120,
      "imageHeight": 120,
      "cornerRadius": 20
    }
  }
}

Splash Screen Options

Custom Splash Screen Images

Android: Place image at public/android/splashscreen.{png|jpg|webp}

• Supported formats: PNG, JPG, WebP
• Fallback: App launcher icon

iOS: Place image at public/ios/splashscreen.{png|jpg|jpeg}

• Recommended: PNG format, 512x512px
• File size: Keep under 1MB
• Fallback: Progress bar with loader

Access Control & Whitelisting

Control network access and navigation in universal apps through URL whitelisting.

{
  "WEBVIEW_CONFIG": {
    "accessControl": {
      "enabled": true,
      "allowedUrls": [
        "https://api.example.com/*",
        "*.example.com",
        "https://cdn.example.com/assets/*"
      ]
    }
  }
}

Access Control Options

Behavior

• enabled: true — Only whitelisted URLs are accessible (default deny)
• enabled: false — All URLs are accessible (no restrictions)

URL Patterns

Exact Match:

{
  "allowedUrls": [
    "https://api.example.com/users",
    "https://cdn.example.com/logo.png"
  ]
}

Wildcard Match:

{
  "allowedUrls": [
    "https://api.example.com/*",
    "https://*.example.com/api/*"
  ]
}

Subdomain Match:

{
  "allowedUrls": [
    "*.example.com",
    "*.cdn.example.com"
  ]
}

Protocol Configuration

Configure webview protocol settings for your universal app. Control whether the webview uses HTTP or HTTPS protocol.

{
  "WEBVIEW_CONFIG": {
    "useHttps": true
  }
}

• Type: Boolean
• Default: false
• Description: Controls the protocol used for webview URLs
• Behavior:
  • true: Uses HTTPS protocol
  • false: Uses HTTP protocol

Example Configuration

Here's a complete example configuration file:

{
  "NODE_SERVER_HOSTNAME": "localhost",
  "NODE_SERVER_PORT": 3005,
  "WEBPACK_DEV_SERVER_HOSTNAME": "localhost",
  "WEBPACK_DEV_SERVER_PORT": 3006,
  "BUILD_OUTPUT_PATH": "build",
  "PUBLIC_STATIC_ASSET_PATH": "/assets/",
  "PUBLIC_STATIC_ASSET_URL": "http://localhost:3006",
  "NODE_ENV": "development",
  "API_URL": "https://api.example.com",
  "ANALYTICS_ID": "UA-123456",
  "CLIENT_ENV_VARIABLES": [
    "API_URL",
    "ANALYTICS_ID"
  ],
  "WEBVIEW_CONFIG": {
    "port": "3005",
    "LOCAL_IP": "192.168.XX.XX",
    "appInfo": "android-v2.1.0",
    "useHttps": true,
    "profiler": {
      "enabled": false
    },
    "android": {
      "appName": "My App",
      "packageName": "com.example.myapp",
      "buildType": "debug",
      "sdkPath": "/Users/yourname/Library/Android/sdk",
      "emulatorName": "Pixel_5_API_30"
    },
    "ios": {
      "appName": "My App",
      "appBundleId": "com.example.myapp",
      "buildType": "Debug",
      "simulatorName": "iPhone 17 Pro"
    },
    "accessControl": {
      "enabled": true,
      "allowedUrls": [
        "https://api.example.com/*",
        "*.cdn.example.com"
      ]
    },
    "splashScreen": {
      "duration": 2000,
      "backgroundColor": "#ffffff",
      "imageWidth": 120,
      "imageHeight": 120,
      "cornerRadius": 20
    }
  }
}

Best Practices

1. Never commit secrets - Use environment-specific config files and add them to .gitignore
2. Use CLIENT_ENV_VARIABLES sparingly - Only expose what's absolutely necessary to the client
3. Use HTTPS in production - Always set useHttps: true for production builds
4. Configure access control - Enable whitelisting for production apps to enhance security
5. Optimize splash screen - Keep duration reasonable and image size under 1MB